﻿#region ... Copyright Notice ...
/*
   Copyright 2008 Tyler Jensen

	Author: Tyler Jensen    http://www.tsjensen.com/blog

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 */
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace Atrax.Library
{
	public interface IQueryProcessor
	{
		//todo: use XML or simple dto's defined in this assembly

		/*
		 * authentication scheme
		 * 
		 *	hashkey = userkey + datetime + private key
		 *		
		 * pass userkey, datetime, and hashkey as authentication and make timeout in 3 minutes
		 * 
		 * add service to web/dispatcher to GetTime
		 * 
		 * make all services available via HttpGet, HttpPost, and asmx web service
		 * 
		 * make caller pass in XML that contains data that will be used by this interface to produce the spiderRecord, reportFragment
		 * and AtraxReport
		 * 
		 * rename these to something more generic???
		 * 
		 * SpiderRecord
		 * AtraxJobRequestData
		 * AtraxReportFragment
		 * 
		 * AtraxSpiderRequest
		 * AtraxSpiderResponseData
		 * 
		 * AtraxReport
		 * 
		 */

		/// <summary>
		/// This method will be called before any other methods. The AtaxQuery object should be stored locally for use other methods.
		/// </summary>
		/// <param name="query"></param>
		void Initialize(Query query);

		/// <summary>
		/// The processor must provide access to the query passed to it in the Initialize method.
		/// </summary>
		Query Query { get; }

		/// <summary>
		/// Called after the Initialize method is called. Allows query processor to validate the query.
		/// </summary>
		/// <param name="errorMessage">If not valid, this message is reported in the error message to the client.</param>
		/// <returns>Return true if the query is valid for this query processor.</returns>
		QueryValidationResult Validate();


		/// <summary>
		/// Should return the estimated seconds for this query to be processed taking only the estimated work and available IP addresses. <br/>
		/// Implementation should cache this value because the method may be called more than once.
		/// </summary>
		/// <param name="availableIpAddressCount"></param>
		/// <returns></returns>
		double GetProcessingTimeEstimate(int availableIpAddressCount);

		/// <summary>
		/// Should use AtraxQuery object passed to Initialize method to create one or more InternetRequest objects to be executed by the Atrax spiders.
		/// </summary>
		/// <returns></returns>
		InternetRequest[] CreateRequests();

		/// <summary>
		/// Should process the InternetResponse, parsing or extracting data from the raw HTTP response <br/>
		/// data into data that can be assembled into a final report. Usually this is an XML fragment.
		/// </summary>
		/// <param name="response"></param>
		/// <param name="mayAddMoreSpiderJobs"></param>
		/// <returns>
		/// Returns a parsed fragment to be used in creating the final report.<br/>
		/// May also include a new InternetRequest array of follow-on requests for the same query.
		/// </returns>
		QueryResultFragment ProcessResponse(InternetResponse response);

		/// <summary>
		/// Combine all result fragments, using data from the original query as well to produce the final result, usually an XML report.
		/// </summary>
		/// <param name="fragments"></param>
		/// <returns></returns>
		QueryResult CreateResult(QueryResultFragment[] fragments);

		/// <summary>
		/// Returns a sample query request string, usually in XML format consumed by this query processor.
		/// </summary>
		/// <returns></returns>
		string GetSampleQueryRequest();
	}
}
